home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d5 / spkrsys.arc / SPKR.DOC < prev    next >
Text File  |  1986-03-23  |  10KB  |  264 lines
  1.                                V1.01 22 Mar 1986
  2.  
  3.                            SPK Device Documentation
  4.                            ------------------------
  5.  
  6.         Purpose
  7.         -------
  8.  
  9.         SPKR.SYS is a DOS installable device driver that allows any
  10.         application to produce arbitrary pitch/duration sounds on the
  11.         PC's speaker.  SPKR requires DOS 2.0 or later and an IBM PC
  12.         compatible machine.
  13.  
  14.  
  15.         Installation
  16.         ------------
  17.  
  18.         To install SPKR, follow two steps: place the file SPKR.SYS in
  19.         the root directory of your boot diskette or hard disk, and
  20.         modify the CONFIG.SYS file to include the statement
  21.         "device=spkr.sys".
  22.  
  23.         In case you are not familiar with CONFIG.SYS: this is a small
  24.         text file that DOS reads when booting.  It contains various
  25.         pieces of information that DOS and other programs can use when
  26.         setting themselves up.  Look in the root directory of your boot
  27.         disk for the file CONFIG.SYS.  If no such file exists, just
  28.         type:
  29.  
  30.                 copy con \config.sys<Enter>
  31.                 device=spkr.sys<Enter>
  32.  
  33.         Then press Ctrl-Z (you'll see "^Z") and <Enter>, and you're
  34.         done.
  35.  
  36.         If you already have a CONFIG.SYS file (which is likely), you
  37.         must edit it to include the statement "device=spkr.sys".  Do
  38.         this using your text editor or word processor in text mode (or
  39.         Edlin, heaven forbid).  Retain all existing information, and add
  40.         the new line.
  41.  
  42.         Now reboot your machine.  If all goes well, it will boot as
  43.         usual.  There will be no immediate indication that anything has
  44.         happened, except that you will see SPKR's logo and copyright.
  45.  
  46.         If you have a hard disk and wish to place SPKR.SYS in a
  47.         directory other than the root, you may do so.  Just alter the
  48.         CONFIG.SYS statement to reflect the full path where SPKR.SYS can
  49.         be found.
  50.  
  51.  
  52.         Using the SPK device
  53.         --------------------
  54.  
  55.         When DOS finds the "device=spkr.sys" line in config.sys, it
  56.         loads and installs the SPKR.SYS program as a virtual device.
  57.         What this means, practically speaking, is that there is now a
  58.         new "device" attached to your PC. You already have several
  59.         devices installed: CON, PRN, COM1 and COM2, AUX, your disk
  60.         drives, and possibly a RAM (or virtual) disk if you have
  61.         installed VDISK.SYS or another disk emulator.
  62.  
  63.         The new device is known to DOS by the name "SPK" (note: this is
  64.         NOT "SPKR", it's "SPK", no R).  Like other output devices, you
  65.         can write (send information) to the device.  SPK is an "output
  66.         only" device like a printer: you can send information to it, but
  67.         you cannot receive information from it.
  68.  
  69.         To use SPK, you must send a series of frequencies and durations
  70.         to the SPK device.  Durations are measured in PC clock ticks,
  71.         which occur about 18.2 times per second; thus, for example, a
  72.         duration of 18 is about one second.
  73.  
  74.         The syntax of data sent to SPK is:
  75.  
  76.             {<frequency>,<duration>;}<CR>
  77.  
  78.         The {} means that you can send one or more sequences of
  79.         frequency and duration to the device.  The <CR> is a carriage
  80.         return, ASCII code 13.
  81.  
  82.         Here are two examples of valid sequences for SPK:
  83.  
  84.             1000,18;<CR>
  85.                 Make a 1000 cps tone for one second
  86.  
  87.             1000,18;2000,36;<CR>
  88.                 Make a 1000 cps tone for one second, then a
  89.                 2000 cps tone for two seconds.
  90.  
  91.         A frequency of 0 is a "rest": no sound will be issued for the
  92.         specified duration.
  93.  
  94.         SPK's sounds are played in background.  That is, control is
  95.         returned immediately to the program that sends data to SPK (the
  96.         "foreground" program).  The sounds will be played while
  97.         foreground execution continues.
  98.  
  99.         There are many ways to send information to SPK.  The simplest is
  100.         to do it right from the keyboard, at the DOS prompt:
  101.  
  102.                 copy con spk<Enter>
  103.                 1000,18<Enter>
  104.                 ^Z<Enter>
  105.  
  106.         The "copy con spk" command tells DOS that you want to copy input
  107.         from the console input (the keyboard) to the SPK device (the
  108.         speaker).  The keyboard input "1000,18<Enter>" is copied to the
  109.         SPK device when you hit the Ctrl-Z (end of copy) and <Enter>
  110.         (execute) keys.
  111.  
  112.         Another way to write to the device is to copy a small textfile
  113.         to SPK.  For example, type
  114.  
  115.                 copy con spkdemo.txt<Enter>
  116.                 1000,10;2000,5;<Enter>
  117.                 ^Z<Enter>
  118.  
  119.         You should now have a small textfile called SPKDEMO, the
  120.         contents of which are "1000,10;2000,5".  To send it to the
  121.         speaker (sounding two tones), just type
  122.  
  123.                 copy spkdemo.txt spk
  124.                         or
  125.                 type spkdemo.txt > spk
  126.  
  127.         You could, of course, put either of those two commands in a DOS
  128.         batch file.
  129.  
  130.         It is also possible to send data to SPK from high level
  131.         languages or from assembler programs.  The following examples
  132.         lack error checking for conciseness; you should add checks to
  133.         ensure that the SPK device is installed (typically by trapping
  134.         for an error in opening the file "SPK").
  135.  
  136.         In BASIC:
  137.  
  138.                 10 FREQ=1000: DUR=10: GOSUB 1000
  139.                 20 END
  140.                 1000 'Sound speaker at FREQ for DUR
  141.                 1010 OPEN "SPK" FOR OUTPUT AS #1
  142.                 1020 PRINT #1, FREQ;",";DUR;";"
  143.                 1030 CLOSE 1
  144.                 1040 RETURN
  145.  
  146.                 This is a bit superfluous in BASIC, however, since
  147.                 BASIC's "SOUND" statement provides essentially the
  148.                 same function.  The main difference is that SPK's
  149.                 sounds play in background.
  150.  
  151.  
  152.         In C:
  153.  
  154.                 spkr (freq, dur)
  155.                 unsigned freq, dur;
  156.                 {
  157.                 FILE *spk, *fopen();
  158.  
  159.                         spk = fopen("SPK","w");
  160.                         fprintf (spk, "%u,%u;\n", freq, dur);
  161.                         fclose(spk);
  162.                 }
  163.  
  164.  
  165.         In Turbo Pascal:
  166.  
  167.                 Procedure Spkr (Freq, Dur: Integer);
  168.                 Var f: Text;
  169.                 Begin
  170.                     Assign (f, 'SPK');
  171.                     Rewrite (f);
  172.                     WriteLn (f, Freq, ',', Dur, ';');
  173.                     Close (f)
  174.                 End;
  175.  
  176.  
  177.         SPK and PCED
  178.         ------------
  179.  
  180.         If you are using the PCED command interface, you can send data
  181.         to the speaker using the SEND user-installed command:
  182.  
  183.             SEND SPK 1000,10;2000,5;\13
  184.  
  185.  
  186.         Limits
  187.         ------
  188.  
  189.         Valid frequencies are 0 (rest), and 20 through 30000.  Only your
  190.         dog will hear frequencies above approximately 15000 cps.
  191.  
  192.         Valid durations are 1 through 65535 (about an hour).
  193.  
  194.         All numeric input is treated modulo 65536; that is, if you
  195.         specify a number larger than 65536, SPKR will actually use the
  196.         remainder of your input divided by 65536.
  197.  
  198.         If your input is outside of the valid range, it will be
  199.         converted to the highest or lowest value, as appropriate.  Thus,
  200.         e.g., a frequency of 35000 will be changed to 30000.
  201.  
  202.         SPK can store up to 128 frequency/duration pairs.  Additional
  203.         sounds will be discarded.
  204.  
  205.         There is a limit of 255 characters per input line to SPKR (i.e.,
  206.         maximum of 255 characters sent before a carriage return).  Data
  207.         beyond 255 characters will be discarded.
  208.  
  209.         Any data sent to SPK other that '0' through '9', ';', ',', and
  210.         carriage returns are ignored.
  211.  
  212.         Invalid frequency/duration pairs are discarded.
  213.  
  214.  
  215.         Frequency Chart
  216.         ---------------
  217.  
  218.         Here is an approximate frequency chart:
  219.  
  220.             A  440           E 659
  221.             B  494           F 698
  222.             C  523           G 784
  223.             D  587
  224.  
  225.         The 523 Hz "C" is middle C.  To increase a note by one octave,
  226.         double the frequency; to decrease by one octave, halve it.
  227.  
  228.  
  229.  
  230.         Copyright/License/Warranty
  231.         --------------------------
  232.  
  233.         This document and the current version of the program file
  234.         SPKR.SYS ("the software") are copyrighted by the author.  The
  235.         copyright owner hereby licenses you to: use the software; make
  236.         as many copies of the program and documentation as you wish;
  237.         give such copies to anyone; and distribute the software and
  238.         documentation via electronic means.
  239.  
  240.         However, you are specifically prohibited from charging, or
  241.         requesting donations, for any such copies, however made.  An
  242.         exception is granted to recognized not-for-profit user's
  243.         groups, which are authorized to charge a small fee (not to
  244.         exceed $7) for materials, handling, postage, and general
  245.         overhead.  NO FOR-PROFIT ORGANIZATION IS AUTHORIZED TO CHARGE
  246.         ANY AMOUNT FOR DISTRIBUTION OF COPIES OF THE SOFTWARE OR
  247.         DOCUMENTATION.
  248.  
  249.         No copy of the software may be distributed or given away without
  250.         this document; and this notice must not be removed.
  251.  
  252.         There is no warranty of any kind, and the copyright owner is not
  253.         liable for damages of any kind.  By using the software, you
  254.         agree to this.
  255.  
  256.         The software and documentation are:
  257.  
  258.                              Copyright (c) 1986 by
  259.                             Christopher J. Dunford
  260.                            10057-2 Windstream Drive
  261.                            Columbia, Maryland 21044
  262.                                 (301) 992-9371
  263.                              CompuServe 76703,2002
  264.